Core

class phoxi_instant_meshing.InstantMeshing(devices: list[DeviceParameters], settings: Settings, message_callback: Callable[[MessageType, str], None] | None = None)

Bases: object

add_scan(frame: PhoXiFrame, device_id: str, transformation: object | None = None) → object | None

Integrate an additional scan to the volumetric structure.

Parameters:

  • frame – Input frame data (PhoXiFrame)

  • device_id – Device identifier

  • transformation – Optional 4x4 transformation matrix. If None, uses identity matrix.

Returns:

Result transformation as 4x4 numpy array, or None if tracking failed

Raises:

PhoIMException – If the C API call fails

Note

Both input and output transformations use row-major format (standard NumPy convention). Conversion to/from column-major (C API) is handled internally.

add_scan_batch(scans: list[tuple[PhoXiFrame, str, object | None]]) → object | None

Integrate a batch of scans to the volumetric structure simultaneously.

Parameters:

scans – List of tuples (frame, device_id, transformation). All scans must correspond to the same batch of devices.

Returns:

Result transformation as 4x4 numpy array, or None if tracking failed. This transformation is from batch space to mesh space.

Raises:

PhoIMException – If the C API call fails

Note

Both input and output transformations use row-major format (standard NumPy convention). Conversion to/from column-major (C API) is handled internally.

clear()

Clear scene. Removes all added data but preserves cropping volume and devices.

Raises:

PhoIMException – If the C API call fails

classmethod create_with_batches(device_batches: list[list[DeviceParameters]], settings: Settings, message_callback: Callable[[MessageType, str], None] | None = None)

Create InstantMeshing instance with device batches.

Parameters:

  • device_batches – List of device batches, where each batch is a list of DeviceParameters

  • settings – InstantMeshing settings

  • message_callback – Optional callback for log messages

Returns:

InstantMeshing instance

Raises:

PhoIMException – If the C API call fails

static deserialize_device_parameters(json_str: str) → DeviceParameters

Deserialize Device Parameters from JSON string.

Parameters:

json_str – JSON string representation of device parameters

Returns:

DeviceParameters object

get_mesh(cropping_volume: CroppingVolume | None = None, progress_callback: Callable[[float], None] | None = None) → Mesh

Compute union of all added scans as a triangle mesh.

Parameters:

  • cropping_volume – 3D volume boundary for mesh generation, or None for no cropping

  • progress_callback – Optional callback for progress reporting. Receives progress value in range [0.0, 1.0].

Returns:

Mesh object with vertices, normals, colors, and indices as numpy arrays.

Raises:

PhoIMException – If the C API call fails

get_union_orthogonal(camera_views: list[CameraParamsOrthogonal]) → PointCloud

Generate virtual scans from orthogonal camera views and return as point cloud.

Parameters:

camera_views – List of orthogonal camera views

Returns:

PointCloud object containing the union of all virtual scans

get_union_perspective(camera_views: list[CameraParamsPerspective]) → PointCloud

Generate virtual scans from perspective camera views and return as point cloud.

Parameters:

camera_views – List of perspective camera views

Returns:

PointCloud object containing the union of all virtual scans

get_virtual_scan_orthogonal(camera_params: CameraParamsOrthogonal, camera_space: bool = False) → Scan

Create a virtual 3D scan from an arbitrary viewpoint using orthogonal projection.

Parameters:

  • camera_params – Parameters of the orthogonal virtual camera

  • camera_space – If True, scan is in camera space; if False, in mesh space

Returns:

Scan object containing the virtual scan data

get_virtual_scan_perspective(camera_params: CameraParamsPerspective, camera_space: bool = False) → Scan

Create a virtual 3D scan from an arbitrary viewpoint using perspective projection.

Parameters:

  • camera_params – Parameters of the perspective virtual camera

  • camera_space – If True, scan is in camera space; if False, in mesh space

Returns:

Scan object containing the virtual scan data

reset_cropping_volume()

Remove the 3D boundary volume filter. All newly added scan data will be processed.

Note:

This only affects future scans; existing filtered data cannot be recovered.

Raises:

PhoIMException – If the C API call fails

reset_tracking()

Reset tracking. All data will be aligned to the camera space of the next added scan. Already added scans remain in their current positions.

Raises:

PhoIMException – If the C API call fails

static serialize_device_parameters(params: DeviceParameters) → str

Serialize Device Parameters to JSON string.

Parameters:

params – DeviceParameters object to serialize

Returns:

JSON string representation of the device parameters

set_cropping_volume(cropping_volume: CroppingVolume)

Define a 3D boundary volume for filtering newly added scan data.

Parameters:

cropping_volume – The 3D volume boundary. Only surfaces inside will be added.

Note:

This only affects future scans; existing data remains unchanged.

Raises:

PhoIMException – If the C API call fails